问题

在设计方法API时，异常是应该着重关注的，同样地，方法的文档注释上异常条件也需要显式的说明，因此，在针对异常编写文档时，有哪些需要注意的地方？

答案

1. 始终要单独地声明受检异常，并且使用javadoc的@throws标记,准确地记录下抛出每个异常的条件。如果方法抛出多个异常类，不要使用它抛出异常类的父类，永远不要声明方法”throwsException”，或更糟糕的声明它”throw Throwable”。这样的声明没有给开发者关于”这个方法抛出哪些异常”的任何有用信息，实际上掩盖了该方法在同样的执行环境下可能抛出的任何其他异常， 因此会妨碍该方法的使用；
2. 使用javacdoc的@throws标签可以显示方法可能抛出的运行时异常，但是不要使用throws关键字将运行时异常包含在方法的声明中。使用API的程序员必须知道哪些异常是需要受检的,哪些是不需要受检的。

结论

要为你编写的每个方法所抛出的每个异常建立文档，对受检的异常和未受检的异常，就像对于抽象和具体的方法都一样。要为每个受检的异常提供单独的throws字句，不要为未受检的异常提供throws语句。如果没有为可以抛出的异常建立文档,那么其他开发人员很难或者根本不可能有效使用你的类或接口。